---
title: Astro 사이트를 Cloudflare Pages에 배포하세요
description: Cloudflare Pages를 사용하여 Astro 사이트를 웹에 배포하는 방법.
type: deploy
i18nReady: true
---

import ReadMore from '~/components/ReadMore.astro'

프런트엔드 개발자가 정적 (JAMstack) 및 SSR 웹사이트를 공동 작업하고 배포할 수 있는 플랫폼인 [Cloudflare Pages](https://pages.cloudflare.com/)에 Astro 프로젝트를 배포할 수 있습니다.

이 가이드에는 다음이 포함됩니다.

- [Cloudflare Pages Dashboard를 통해 배포하는 방법](#git으로-사이트를-배포하는-방법)
- [Wrangler, Cloudflare CLI를 사용하여 배포하는 방법](#wrangler를-사용하여-사이트를-배포하는-방법)
- [`@astrojs/cloudflare`를 사용하여 SSR 사이트를 배포하는 방법](#ssr-사이트-배포-방법)

## 전제 조건

시작하려면 다음이 필요합니다.

- Cloudflare 계정. 아직 계정이 없다면 프로세스 중에 무료 Cloudflare 계정을 만들 수 있습니다.
- [GitHub](https://github.com/) 또는 [GitLab](https://about.gitlab.com/) 저장소에 푸시된 앱 코드.

## Git으로 사이트를 배포하는 방법

1. Cloudflare Pages에서 새 프로젝트를 설정하세요.
2. 코드를 Git 저장소 (GitHub, GitLab)에 푸시합니다.
3. Cloudflare 대시보드에 로그인하고 **Account Home** > **Pages**에서 계정을 선택하세요.
4. **Create a new Project**와 **Connect Git** 옵션을 선택합니다.
5. 배포하려는 git 프로젝트를 선택하고 **Begin setup**을 클릭합니다.
6. 다음 빌드 설정을 사용합니다.

    - **Framework preset**: `Astro`
    - **Build command:** `npm run build`
    - **Build output directory:** `dist`

7. **Save and Deploy** 버튼을 클릭합니다.

## Wrangler를 사용하여 사이트를 배포하는 방법

1. [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/get-started/)를 설치합니다.
2. `wrangler login`을 사용하여 Cloudflare 계정으로 Wrangler를 인증하세요.
3. 빌드 명령을 실행합니다.
4. `npx wrangler pages deploy dist`를 사용하여 배포합니다.

```bash
# Wrangler CLI 설치
npm install -g wrangler
# CLI에서 Cloudflare 계정에 로그인
wrangler login
# Run your build command
npm run build
# 새 배포 만들기
npx wrangler pages deploy dist
```

자산이 업로드되면 Wrangler는 사이트를 검사할 수 있는 미리보기 URL을 제공합니다. Cloudflare Pages 대시보드에 로그인하면 새 프로젝트가 표시됩니다.

### Wrangler를 사용하여 로컬에서 미리보기 활성화

미리보기가 작동하려면 `wrangler`를 설치해야 합니다.

```bash
pnpm add wrangler --save-dev
```

그런 다음 Astro의 내장 미리보기 명령 대신 `wrangler`를 실행하도록 미리보기 스크립트를 업데이트할 수 있습니다.

```json title="package.json"
"preview": "wrangler pages dev ./dist"
```

## SSR 사이트 배포 방법

[`@astrojs/cloudflare` 어댑터](/ko/guides/integrations-guide/cloudflare/)를 사용하여 Cloudflare Pages에 배포할 Astro SSR 사이트를 빌드할 수 있습니다.

아래 단계에 따라 어댑터를 설정하세요. 그런 다음 위에 설명된 접근 방식 중 하나를 사용하여 배포할 수 있습니다.

### 빠른 설치

다음 `astro add` 명령을 사용하여 Astro 프로젝트에서 SSR을 활성화하려면 Cloudflare 어댑터를 추가하세요. 그러면 어댑터가 설치되고 `astro.config.mjs` 파일이 한 번에 적절하게 변경됩니다.

```bash
npx astro add cloudflare
```

### 수동 설치

대신 어댑터를 수동으로 설치하려면 다음 두 단계를 완료하세요.

1. 선호하는 패키지 관리자를 사용하여 프로젝트 종속성에 `@astrojs/cloudflare` 어댑터를 추가하세요. npm을 사용 중이거나 확실하지 않은 경우 터미널에서 다음을 실행하세요.

    ```bash
    npm install @astrojs/cloudflare
    ```

2. `astro.config.mjs` 파일에 다음을 추가하세요:

    ```js title="astro.config.mjs" ins={2, 5-6}
    import { defineConfig } from 'astro/config';
    import cloudflare from '@astrojs/cloudflare';

    export default defineConfig({
      output: 'server',
      adapter: cloudflare()
    });
    ```

<ReadMore>[Astro의 SSR](/ko/guides/server-side-rendering/)에 대해 자세히 알아보세요.</ReadMore>

## 문제 해결

### 클라이언트 측 수화

Cloudflare의 Auto Minify 설정으로 인해 클라이언트 측 하이드레이션이 실패할 수 있습니다. 콘솔에 `Hydration completed but contains mismatches`가 표시되면 Cloudflare 설정에서 Auto Minify를 비활성화하세요.

### Node.js 런타임 API

[Cloudflare SSR 어댑터](/ko/guides/integrations-guide/cloudflare/)와 함께 주문형 렌더링을 사용하는 프로젝트를 빌드한다면 `[Error] Could not resolve "XXXX. The package "XXXX" wasn't found on the file system but is built into node.`와 같은 오류 메시지와 함께 서버는 빌드에 실패합니다.

- 이는 서버 측 환경에서 사용 중인 패키지 또는 가져오기가 [Cloudflare 런타임 API](https://developers.cloudflare.com/workers/runtime-apis/nodejs/)와 호환되지 않음을 의미합니다.

- Node.js 런타임 API를 직접 가져오는 경우, 해결 방법에 대한 추가 단계는 Cloudflare의 [Node.js 호환성](/ko/guides/integrations-guide/cloudflare/#nodejs-호환성)에 대한 Astro 문서에서 참조할 수 있습니다.

- Node.js 런타임 API를 가져오는 패키지를 가져오는 경우, 패키지 작성자에게 문의하여 `node:*` import 구문을 지원하는지 확인하세요. 그렇지 않은 경우 대체 패키지를 찾아야 할 수도 있습니다.
